Skip to content

Latest commit

 

History

History
758 lines (550 loc) · 36.9 KB

Implementing SPI-API.adoc

File metadata and controls

758 lines (550 loc) · 36.9 KB
Raw

Implementing SPI-API

General requirements

SPI means Service Provider Interface that is an API intended to be implemented or extended by a third party. SPI-API is used for connection between XS2A interface and ASPSP system, that’s why this system is also called connector and this word will be used in all chapters below. XS2A provides interfaces in java (de.adorsys.psd2.xs2a.spi.service package), that should be implemented in the connector’s code.

Basic responsibilities of the connector:

  • receive the input data from XS2A;

  • provide this data to the ASPSP system (and/or add some business logic, if necessary);

  • retrieve the response from ASPSP system;

  • provide the ASPSP system’s response back to XS2A using SpiResponse class.

SPI methods common parameters

Input data for the connector is provided from TPP through XS2A and some parameters in the interfaces' signatures are common for all of them:

  • spiContextData - the information about PSU and TPP;

  • spiAspspConsentDataProvider - this service is used for providing ASPSP consent data to connector and ASPSP system.

Other method-specific parameters are described in the chapters below.

Speaking about SpiContextData - first, it contains the psuData object. It stores data about PSU known in scope of the request:

Attribute Type Condition Description

psuId

String

Conditional

Client ID of the PSU in the ASPSP client interface

psuIdType

String

Conditional

Type of the psuId, needed in scenarios where PSUs have several psuIds as access possibility

psuCorporateId

String

Conditional

Identification of a corporate in the online Channels. Might be mandated in the ASPSP’s documentation. Only used in a corporate context

psuCorporateIdType

String

Conditional

This is describing the type of the identification needed by the ASPSP to identify the psuCorporateId

Another parameter in SpiContextData is the tppInfo. It contains information about the TPP’s certificate:

  • "Registration number": example = "1234_registrationNumber";

  • "TPP name": example = "Tpp company";

  • "National competent authority": example = "Bafin";

Also, SpiContextData object stores the OAuth2 token in the oAuth2Token field - this is the authorisation token that should be present in any XS2A request during OAuth SCA approach. This header is passed to SPI level in each method.

There are a few optional fields in SpiContextData, which can be sent as headers in request by TPP:

Attribute Type Condition Description

tppBrandLoggingInformation

String

Optional

This parameter might be used by TPPs to inform the ASPSP about the brand used by the TPP towards the PSU. This information is meant for logging entries to enhance communication between ASPSP and PSU or ASPSP and TPP. This parameter might be ignored by the ASPSP.

tppRejectionNoFundsPreferred

Boolean

Optional

If it equals "true" then the TPP prefers a rejection of the payment initiation in case the ASPSP is providing an integrated confirmation of funds request an the result of this is that not sufficient funds are available. If it equals "false" then the TPP prefers that the ASPSP is dealing with the payment initiation like in the ASPSPs online channel, potentially waiting for a certain time period for funds to arrive to initiate the payment. This parameter may be ignored by the ASPSP.

tppRedirectPreferred

Boolean

Optional

If it equals "true", the TPP prefers a redirect over an embedded SCA approach. If it equals "false", the TPP prefers not to be redirected for SCA. The ASPSP will then choose between the Embedded or the Decoupled SCA approach, depending on the parameter TPP- Decoupled-Preferred and the choice of the SCA procedure by the TPP/PSU. If the parameter is not used, the ASPSP will choose the SCA approach to be applied depending on the SCA method chosen by the TPP/PSU.

tppDecoupledPreferred

Boolean

Optional

If it equals "true", the TPP prefers a decoupled SCA approach. If it equals "false", the TPP prefers not to use the decoupled approach for SCA. The ASPSP will then choose between the embedded or the redirect SCA approach, depending on the choice of the SCA procedure by the TPP/PSU. If the parameter is not used, the ASPSP will choose the SCA approach to be applied depending on the parameter TPP-Redirect- Preferred and the SCA method chosen by the TPP/PSU. The parameter might be ignored by the ASPSP. If both parameters TPP-Redirect-Preferred and TPP-Decoupled-Preferred are present and true, the request is still not rejected, but it is up to the ASPSP, which approach will actually be used.

The response from the connector to XS2A and the ASPSP consent data provider are described in the next chapters.

SpiResponse

This class acts as the container for all responses from the connector to XS2A. It is a generic class and it uses builder pattern to create the response. Main fields of the class:

  • T payload;

  • List<TppMessage> errors.

payload should be used to create successful response to XS2A. It should contain the object which current SPI method deals with. errors should be used in case the response fails. The list should contain at least one error element inside the TppMessage container. It is possible to provide several errors, if necessary. build() method should be used to create SpiResponse after setting payload or errors. Typical usage of builder pattern for happy-path response:

return SpiResponse.<SpiAuthorisationStatus>builder() .payload(SpiAuthorisationStatus.SUCCESS) .build();

In this example the SpiAuthorisationStatus enumerator value is returned.

Working with ASPSP-Consent-Data object

ASPSP consent data is a container that allows to handle any information about the consent or payment in scope of SPI level calls. More detailed clarification about this object can be found here. XS2A provides a special interface for working with the ASPSP consent data - de.adorsys.psd2.xs2a.spi.domain.SpiAspspConsentDataProvider. This interface has 3 methods:

  • loadAspspConsentData to retrieve the ASPSP consent data;

  • updateAspspConsentData to update this data;

  • clearAspspConsentData to erase the ASPSP consent data.

This interface has the implementation: SpiAspspConsentDataProviderImpl. It should be used while working with the existing entity of AIS consent or payment (by providing its ID) in the connector. One should understand that it is SPI developer responsibility to update (or not) the ASPSP consent data on the connector side. XS2A just provides a possibility to make these changes by passing the SpiAspspConsentDataProvider object to every SPI method. Please note, that XS2A just stores this data in CMS as a byte array field and does not use it. Definite ASPSP consent data is tied to the definite AIS consent or payment and stored in aspsp_consent_data CMS table.

From the connector side typical code for working with the ASPSP consent data during any SPI implementation method is the following:

  • byte[] initialAspspConsentData = aspspConsentDataProvider.loadAspspConsentData(); - to retrieve the data;

  • aspspConsentDataProvider.updateAspspConsentData("Some text data to be stored".getBytes()); - to update the data with the new one.

Implementation of AccountSpi

The Interface is used for AIS consent accounts SPI implementation. The following methods should be implemented:

  • requestAccountList;

  • requestAccountDetailForAccount;

  • requestTransactionsForAccount;

  • requestTransactionForAccountByTransactionId;

  • requestBalancesForAccount;

  • requestTransactionsByDownloadLink.

The method requestAccountList provides a possibility to retrieve the list of account details by given AIS consent ID and boolean flag withBalance. Parameters of the method are:

  • spiContextData;

  • withBalance - this flag specifies if the balances would be present in the response or not;

  • spiAccountConsent;

  • spiAspspConsentDataProvider.

Response is a list containing the SpiAccountDetails entities.

The method requestAccountDetailForAccount provides a possibility to retrieve the data for the definite account by given consent ID, account ID (obtained from the previous method) and boolean flag withBalance. Flag’s operation is the same as above. Parameters are:

  • spiContextData;

  • withBalance - this flag specifies if the balances would be present in the response or not;

  • spiAccountReference - holder for account ID;

  • spiAccountConsent;

  • spiAspspConsentDataProvider.

Response is the SpiAccountDetails object.

The method requestTransactionsForAccount provides a possibility to retrieve the list of bank transactions filtered by the period, AIS consent account ID, status and other parameters. Parameters are:

  • spiContextData;

  • spiTransactionReportParameters - additional parameters for retrieving transaction list (e.g. acceptMediaType, withBalance, dateFrom, dateFrom, bookingStatus, entryReferenceFrom, deltaList);

  • spiAccountReference - holder for account ID;

  • spiAccountConsent;

  • spiAspspConsentDataProvider.

The response is SpiTransactionReport object. It also provides the transaction list download ID, which can be used to download a file with the list of bank transactions.

The method requestTransactionForAccountByTransactionId provides a possibility to retrieve the data about the bank transaction by the given transaction ID (can be obtained from the previous method). Parameters:

  • spiContextData;

  • transactionId - ID of bank transaction;

  • spiAccountReference - holder for account ID;

  • spiAccountConsent;

  • spiAspspConsentDataProvider.

Response is SpiTransaction object.

The method requestBalancesForAccount provides a possibility to retrieve the list of balances for the given account by its ID. Parameters are:

  • spiContextData;

  • spiAccountReference - holder for account ID;

  • spiAccountConsent;

  • spiAspspConsentDataProvider.

Response is a list with SpiAccountBalance objects.

The method requestTransactionsByDownloadLink allows to download a list of bank transactions directly to the file. Its parameters are:

  • spiContextData;

  • spiAccountConsent;

  • downloadId - identifier for downloading the file (can be retrieved from the requestTransactionsForAccount SPI method call);

  • spiAspspConsentDataProvider.

It returns SpiTransactionsDownloadResponse object with the InputStream which contains the transaction list, filename (can be null) and the size of the payload in bytes (can be null also). From the TPP side the download can be initiated by accessing new endpoint in account controller - GET /v1/accounts/{account-id}/transactions/download/{download-id}. TPP should provide the AIS consent account ID and the download ID. As a response for accessing this endpoint, the TPP receives the stream with transaction list.

Implementation of AisConsentSpi

The Interface is used for AIS consent SPI implementation. The following methods should be implemented:

  • initiateAisConsent;

  • getConsentStatus;

  • revokeAisConsent;

  • verifyScaAuthorisation.

The method initiateAisConsent provides a possibility to create a new AIS consent from the provided data. Parameters of the method are:

  • spiContextData;

  • spiAccountConsent - provided data about the AIS consent from CMS;

  • spiAspspConsentDataProvider.

Response is a SpiInitiateAisConsentResponse object.

The method getConsentStatus provides a possibility to retrieve the consent status. Parameters of the method are:

  • spiContextData;

  • spiAccountConsent - provided data about the AIS consent from CMS;

  • spiAspspConsentDataProvider.

Response is a SpiAisConsentStatusResponse object with status and PSU message (optional).

The method revokeAisConsent provides a possibility to revoke the given AIS consent (change its status to REJECTED or TERMINATED_BY_TPP). Parameters of the method are:

  • spiContextData;

  • spiAccountConsent - provided data about the AIS consent from CMS;

  • spiAspspConsentDataProvider.

Response is empty (VoidResponse object).

The method verifyScaAuthorisation provides a possibility to send information about the authorisation confirmation (e.g. transaction authorisation number or some other security code) to ASPSP. This method is used only with embedded SCA Approach. Parameters of the method are:

  • spiContextData;

  • SpiScaConfirmation - the information about the definite consent (its ID), corresponding PSU data and security code.

  • spiAccountConsent - provided data about the AIS consent from CMS;

  • spiAspspConsentDataProvider.

Response is a SpiVerifyScaAuthorisationResponse object that stores the status of operation.

Among the methods that were described above, this interface extends AuthorisationSpi, its methods are described below in the PaymentAuthorisationSpi chapter.

Providing account resources to consent

Speaking about the AIS consent SPI implementation, please note that TPP can create the consent with provided account reference data (such consent is called dedicated consent) or without one (global or bank offered consent). If the consent was created without account reference data there is a possibility to fill it through the CMS-PSU-API after. The CMS endpoint /psu-api/v1/ais/consent/{internal_consent_id}/save-access provides such functionality. Path parameter internal_consent_id should be the internal CMS consent identifier. The body of this request should contain the JSON representation of account reference, for example:

{
    "accountAccess": {
        "accounts": [
            {
                "iban": "DE80760700240271232400",
                "currency": "EUR"
            }
        ],
        "balances": [
            {
                "iban": "DE80760700240271232400",
                "currency": "EUR"
            }
        ],
        "transactions": [
            {
                "iban": "DE80760700240271232400",
                "currency": "EUR"
            }
        ]
    },
    "frequencyPerDay": 100,
    "validUntil": "2019-12-31"
}

After this operation the given consent’s account reference data will be updated in CMS and the consent may be confirmed as usual.

Implementation of FundsConfirmationSpi

This interface is used for retrieving information from ASPSP in scope of Confirmation of Funds requests.

FundsConfirmationSpi contains only one method that should be implemented - performFundsSufficientCheck, which is responsible for checking whether requested account has sufficient funds. The method returns SpiFundsConfirmationResponse as part of SpiResponse with information whether the requested amount can be booked on the account.

performFundsSufficientCheck takes the following arguments:

  • spiContextData - information about the context of the call

  • spiPiisConsent - optional PIIS consent object, will be absent if the request is done from a workflow without the consent

  • spiFundsConfirmationRequest - information about the account and transaction amount, provided by the TPP

  • aspspConsentDataProvider - optional ASPSP consent data provider, will be absent if the request is done from a workflow without the consent

PIIS consent will be passed to the SPI method along with ASPSP consent data provider if the ASPSP supports PIIS consents. Otherwise both PIIS consent object and ASPSP consent data provider will be absent in the request to SPI.

Implementation of PaymentSpi(s)

We distinguish between following interfaces: SinglePaymentSpi, BulkPaymentSpi, PeriodicPaymentSpi, CommonPaymentSpi, PaymentAuthorisationSpi, PaymentCancellationSpi.

SinglePaymentSpi

The Interface is used for the single payment SPI implementation. The following Methods should be implemented:

  • initiatePayment: aims to initiate a payment;

  • getPaymentById: aims to read the payment by ID;

  • getPaymentStatusById: aims to read the payment status by ID and PSU message (optional);

  • executePaymentWithoutSca: executes payment without SCA;

  • verifyScaAuthorisationAndExecutePayment: verifies SCA authorisation and executes payment.

The method initiatePayment returns a positive or negative payment initiation response (SpiSinglePaymentInitiationResponse object) as a part of SpiResponse. Method signature contains the following (description of basic fields SpiContextData and SpiAspspConsentDataProvider is provided above):

  • spiContextData;

  • spiSinglePayment: payment, that extends SpiPayment (Single Payment) and has fields required for business logic;

  • spiAspspConsentDataProvider.

Response by the method getPaymentById returns payment as a part of SpiResponse (SpiSinglePayment object) and contains the following data:

  • spiContextData;

  • acceptMediaType: media type requested by the TPP;

  • payment: Single Payment;

  • spiAspspConsentDataProvider.

Response by the method getPaymentStatusById returns the SpiGetPaymentStatusResponse object (with the transaction status) and contains the following:

  • spiContextData;

  • acceptMediaType: media type requested by the TPP;

  • payment: Single Payment;

  • spiAspspConsentDataProvider.

executePaymentWithoutSca method is used for executing payment when no SCA is required. Returns a SpiPaymentExecutionResponse object with appropriate transaction status and has the following parameters:

  • spiContextData;

  • payment: Single Payment;

  • spiAspspConsentDataProvider.

verifyScaAuthorisationAndExecutePayment is used for verifying SCA and executing payment. Returns a SpiPaymentExecutionResponse object with appropriate transaction status and has the following parameters:

  • spiContextData;

  • spiScaConfirmation: data for verifying SCA;

  • payment: Single Payment;

  • spiAspspConsentDataProvider.

PeriodicPaymentSpi

The Interface is used for periodic payments for SPI implementation. The following methods should be implemented:

  • initiatePayment;

  • getPaymentById;

  • getPaymentStatusById;

  • executePaymentWithoutSca;

  • verifyScaAuthorisationAndExecutePayment.

The method initiatePayment returns a positive or negative payment initiation response (SpiPeriodicPaymentInitiationResponse) as a part of SpiResponse and contains the following:

  • spiContextData;

  • payment: Periodic Payment;

  • spiAspspConsentDataProvider.

Response by the method getPaymentById returns payment as a part of SpiResponse (SpiPeriodicPayment) and contains the following data:

  • spiContextData;

  • acceptMediaType: media type requested by the TPP;

  • payment: Periodic Payment;

  • spiAspspConsentDataProvider.

Response by the method getPaymentStatusById returns the SpiGetPaymentStatusResponse with the transaction status and PSU message (optional) and contains the following:

  • spiContextData;

  • acceptMediaType: media type requested by the TPP;

  • payment: Periodic Payment;

  • spiAspspConsentDataProvider.

executePaymentWithoutSca method is used for executing payment when no SCA is required. Returns a SpiPaymentExecutionResponse object with appropriate transaction status and has the following parameters:

  • spiContextData;

  • payment: Periodic Payment;

  • spiAspspConsentDataProvider.

verifyScaAuthorisationAndExecutePayment is used for verifying SCA and executing payment. Returns a SpiPaymentExecutionResponse object with appropriate transaction status and has the following parameters:

  • spiContextData;

  • spiScaConfirmation: data for verifying SCA;

  • payment: Periodic Payment;

  • spiAspspConsentDataProvider.

BulkPaymentSpi

The Interface is used for bulk payments for SPI implementation. The following methods should be implemented:

  • initiatePayment;

  • getPaymentById;

  • getPaymentStatusById;

  • executePaymentWithoutSca;

  • verifyScaAuthorisationAndExecutePayment.

The method initiatePayment returns a positive or negative payment initiation response (SpiBulkPaymentInitiationResponse) as a part of SpiResponse and contains the following:

  • spiContextData;

  • payment: Bulk Payment;

  • spiAspspConsentDataProvider.

Response by the method getPaymentById returns payment as a part of SpiResponse (SpiBulkPayment) and contains the following data:

  • spiContextData;

  • acceptMediaType: media type requested by the TPP;

  • payment: Bulk Payment;

  • spiAspspConsentDataProvider.

Response by the methods getPaymentStatusById returns the SpiGetPaymentStatusResponse object with the transaction status and PSU message (optional) and contains the following:

  • spiContextData;

  • acceptMediaType: media type requested by the TPP;

  • payment: Bulk Payment;

  • spiAspspConsentDataProvider.

executePaymentWithoutSca method is used for executing payment when no SCA is required. Returns a SpiPaymentExecutionResponse object with appropriate transaction status and has the following parameters:

  • spiContextData;

  • payment: Bulk Payment;

  • spiAspspConsentDataProvider.

verifyScaAuthorisationAndExecutePayment is used for verifying SCA and executing payment. Returns a SpiPaymentExecutionResponse object with appropriate transaction status and has the following parameters:

  • spiContextData;

  • spiScaConfirmation: data for verifying SCA;

  • payment: Bulk Payment;

  • spiAspspConsentDataProvider.

CommonPaymentSpi

The Interface is used for common payments SPI implementation.

This interface will be called instead of other payment SPI interfaces if the affected payment is considered to be a common one. Depending on mapping configuration of payments for SPI this can mean either all payments, or only payments with any payment product that doesn’t belong to the pre-defined list of standard JSON payment products (regardless of payment service or content type).

The following methods should be implemented:

  • initiatePayment: initiates a payment;

  • getPaymentById: reads the payment by ID;

  • getPaymentStatusById: reads the payment status by ID;

  • executePaymentWithoutSca: executes payment without SCA;

  • verifyScaAuthorisationAndExecutePayment: verifies SCA authorisation and executes payment.

The method initiatePayment is being called on initiating any common payment. Returns a positive or negative payment initiation response (SpiPaymentInitiationResponse) as a part of SpiResponse and has the following parameters:

  • spiContextData;

  • payment: common payment object;

  • spiAspspConsentDataProvider.

getPaymentById method returns payment as a part of SpiResponse (SpiPaymentInfo) and has the following parameters:

  • spiContextData;

  • acceptMediaType: media type requested by the TPP;

  • payment: common payment object;

  • spiAspspConsentDataProvider.

getPaymentStatusById method returns a SpiGetPaymentStatusResponse object with the transaction status and PSU message (optional) and has the following parameters:

  • spiContextData;

  • acceptMediaType: media type requested by the TPP;

  • payment: common payment object;

  • spiAspspConsentDataProvider.

executePaymentWithoutSca method is used for executing payment when no SCA is required. Returns a SpiPaymentExecutionResponse object with appropriate transaction status and has the following parameters:

  • spiContextData;

  • payment: common payment object;

  • spiAspspConsentDataProvider.

verifyScaAuthorisationAndExecutePayment is used for verifying SCA and executing payment. Returns a SpiPaymentExecutionResponse object with appropriate transaction status and has the following parameters:

  • spiContextData;

  • spiScaConfirmation: data for verifying SCA;

  • payment: common payment object;

  • spiAspspConsentDataProvider.

PaymentAuthorisationSpi

The Interface is used while implementing payment authorisation flow on SPI level. This Interface is implemented by extending the AuthorisationSpi. The following Methods should be implemented:

  • authorisePsu;

  • requestAvailableScaMethods;

  • requestAuthorisationCode.

The Method authorisePsu authorises PSU and returns current (success or failure) authorisation status with scaExempted flag. This flag is taken into account by XS2A for performing SCA exemption. If the PSU authorisation SPI response for bulk or single payment will be successful and scaExempted is true - SCA will not be performed will be invoked and authorisation status will be set to EXEMPTED. SCA exemption is supported for multilevel SCA too.

The Method authorisePsu should be used only with Embedded SCA Approach. It contains following Data:

  • spiContextData;

  • psuLoginData: ASPSP identifier(s) of the PSU, provided by TPP within this request;

  • password: PSU’s password;

  • businessObject: payment object;

  • spiAspspConsentDataProvider.

The Method requestAvailableScaMethods returns a list of SCA methods for the PSU by its login. Should be used only with the Embedded SCA Approach. It contains following Data:

  • spiContextData;

  • businessObject;

  • spiAspspConsentDataProvider.

The Method requestAuthorisationCode performs SCA depending on selected SCA method. Should be used only with Embedded Approach. Method returns a positive or negative response as a part of SpiResponse. If the authentication method is unknown, then empty SpiAuthorizationCodeResult should be returned. It contains following data:

  • spiContextData;

  • businessObject;

  • spiAspspConsentDataProvider.

  • authenticationMethodId: ID of a chosen SCA method.

In case of Decoupled SCA Approach, the method startScaDecoupled has to be implemented: method notifies a decoupled application about starting SCA. AuthorisationId is provided to allow the app to access CMS. It returns a response object, contains a message from ASPSP to PSU, gives him instructions regarding decoupled SCA starting. It contains the following data:

  • spiContextData;

  • businessObject;

  • spiAspspConsentDataProvider.

  • authenticationMethodId: for a decoupled SCA method within embedded approach;

  • authorisationId: a unique identifier of authorisation process.

PaymentCancellationSpi

The Interface is used to cancel a payment. The following Methods should be implemented:

  • initiatePaymentCancellation;

  • cancelPaymentWithoutSca;

  • verifyScaAuthorisationAndCancelPayment.

The Method initiatePaymentCancellation returns the payment cancellation response with information about transaction status and whether authorisation of the request is required. It contains the following data:

  • spiContextData;

  • payment: payment to be cancelled;

  • spiAspspConsentDataProvider.

The Method cancelPaymentWithoutSca is used by cancelling payment without performing SCA. Method returns a positive or negative payment cancellation response as part of spiResponse. It contains the following data:

  • spiContextData;

  • payment: payment to be cancelled;

  • spiAspspConsentDataProvider.

The Method verifyScaAuthorisationAndCancelPayment sends authorisation confirmation information (secure code or such) to ASPSP and, in case of successful validation, cancels payment at ASPSP. It returns a positive or negative response as part of spiResponse. It contains the following data:

  • spiContextData;

  • payment payment to be cancelled;

  • spiAspspConsentDataProvider.

  • spiScaConfirmation: payment cancellation confirmation information.

Strong Customer Authentication (SCA)

The Payment initiation depends heavily on the Strong Customer Authentication (SCA) approach implemented by the ASPSP. For now there are three Approaches implemented (REDIRECT, DECOUPLED and EMBEDDED).

SCA Approach REDIRECT

Prerequisites in case of consent for payment initiation:

  • PSU initiated a payment by using TPP;

  • PSU is authenticated via two factors: for example PSU ID and password;

  • Each Payment initiation needs its consent.

When the Payment was initiated, it should be authorised by the PSU. In case of redirect approach the authorisation can be explicit or implicit.

The explicit Start of the authorisation process means that Payment initiation Request is followed by an explicit Request of the TPP to start the authorisation. It is followed by a redirection to the ASPSP SCA authorisation site. A status request might be requested by the TPP after the session is redirected to the TPP’s system. Redirect SCA Approach is used in case of tppExplicitAuthorisationPreferred = true and signingBasketSupported = true or in case of multilevel SCA.

  • tppExplicitAuthorisationPreferred: value of TPP’s choice of authorisation method;

  • signingBasketSupported: indicates if signing basket is supported on the ASPSP profile. It returns true if ASPSP supports signing basket, false if doesn’t.

In case of implicit Start of the Authorisation process the ASPSP needs no additional data from TPP. In this case, the redirection of the PSU browser session happens directly after the Payment Initiation Response. Besides an SCA status request may be sent by the TPP to follow the SCA process. In this case, the authorisation is used based on tppExplicitAuthorisationPreferred and signingBasketSupported values:

  • Implicit authorisation is used in all cases where tppExplicitAuthorisationPreferred or signingBasketSupported not equals true;

  • Implicit approach is impossible in case of multilevel SCA.

For The Redirect Approach the developer needs to implement the following Methods:

  • createCommonPaymentAuthorisation;

  • updateCommonPaymentPsuData;

  • getAuthorisationSubResources;

  • getAuthorisationScaStatus;

  • getScaApproachServiceTypeProvider.

The Method createCommonPaymentAuthorisation creates payment authorisation response and contains:

  • paymentId: ASPSP identifier of a payment;

  • paymentType: e.g. single payment, periodic payment, bulk payment;

  • psuData: psuIdData container of authorisation data about PSU.

The Method updateCommonPaymentPsuData provides transporting data when updating consent psu data. For the Redirect Approach this method is applicable for the selection of authentication methods, before choosing the actual SCA approach. It contains request with following data:

Table 1. Parameters
Attribute Type Description

paymentId

String

Resource identification of the related payment initiation

authorisationId

String

Resource identification if the related payment initiation, Signing Basket or Consent authorisation sub-resource

scaAuthenticationData

String

SCA authentication data, depending on the chosen authentication method

psuData

String

e.g. PsuId, PsuIdType, PsuCorporateId and PsuCorporateIdType

password

PSU Data

Password of the psu

authenticationMethodId

String

The authentication method ID as provided by the ASPSP

scaStatus

Sca Status

e.g. psuIdentified

paymentService

String

e.g. "payments", "bulk-payments" and "periodic-payments"

paymentProduct

String

The related payment product of the payment initiation to be authorized

updatePsuidentification

href Type

The link to the payment initiation, which needs to be updated by the PSU identification if not delivered yet

The Method getAuthorisationSubResources with the paymentId returns authorisation sub resources (e.g. list of authorisation IDs).

The Method getAuthorisationScaStatus with paymentId (ASPSP identifier of the payment, associated with the authorisation) and authorisationId (authorisation identifier), returns SCA status.

Example of Sca Status:

  • RECEIVED(“received”, false): if an authorisation or cancellation-authorisation resource has been created successfully.

  • PSUIDENTIFIED(“psuIdentified”, false): if the PSU related to the authorisation or cancellation-authorisation resource has been identified.

The Method getScaApproachServiceTypeProvider provides SCA approach used in current service. It returns the ScaApproach “Redirect”.

Redirect Approach for Payment cancellation

The Method createCommonPaymentCancellationAuthorisation with paymentId, paymentType and psudata creates payment cancellation authorisation.

The Method getCancellationAuthorisationSubResources with the paymentId returns authorisation sub resources.

The Method updateCommonPaymentCancellationPsuData updates the cancellation for the payment.

The Method getCancellationAuthorisationScaStatus with PaymentId and CancellationId (Resource identification of the related Payment Cancellation authorisation sub-resource) returns SCA status.

The Method getScaApproachServiceTypeProvider provides SCA approach used in current service. It returns the ScaApproach “Redirect”.

SCA Approach EMBEDDED

Embedded SCA approach indicates that the whole authorisation process is going to be performed through the XS2A interface, without any redirect to the online banking. For this purposes, XS2A interface provides the following endpoints:

  • PUT /v1/{payment-service}/{payment-product}/{paymentId}/authorisations/{authorisationId} for payment initiation flow;

  • PUT /v1/{payment-service}/{payment-product}/{paymentId}/cancellation-authorisations/{cancellationId} for payment cancellation flow;

  • PUT /v1/consents/{consentId}/authorisations/{authorisationId} for consent initiation flow.

Embedded SCA Approach uses the same list of methods as Redirect SCA Approach:

  • createCommonPaymentAuthorisation;

  • updateCommonPaymentPsuData;

  • getAuthorisationSubResources;

  • getAuthorisationScaStatus;

  • getScaApproachServiceTypeProvider.

After the successful authorisation start (either explicit or implicit), TPP should update the authorisation with data, provided by PSU. Depending on the amount of SCA methods PSU has, the amount of PSU data, has to be provided, differs. In case when PSU has zero SCA methods, only password should be provided. In case when PSU has one SCA method, the password should be provided as well as authentication data (e.g. TAN received by email or SMS). In case when PSU has more than one SCA method, PSU should first provide password, then select the preferred SCA method and then - the authentication data. For each PSU data update, the same update endpoint should be called, but with corresponding body.

For example, PSU with two SCA methods initiates a payment. Assume that the payment was created and the authorisation has started. Now TPP should update PSU data three times:

  • first PUT /v1/{payment-service}/{payment-product}/{paymentId}/authorisations/{authorisationId} call with PSU password in HTTP body

{
 	"psuData": {
 		"password": "mypassword"
 	}
}

  • second PUT /v1/{payment-service}/{payment-product}/{paymentId}/authorisations/{authorisationId} call with selected SCA method in HTTP body

{
    "authenticationMethodId": "selectedSCAMethod"
}

  • third PUT /v1/{payment-service}/{payment-product}/{paymentId}/authorisations/{authorisationId} call with authentication data in HTTP body

{
	"scaAuthenticationData": "TANNumber"
}

After this steps, the payment initiation authorisation process will be finished.

SCA Approach DECOUPLED

Decoupled SCA approach implies that authorsation will be performed with a help of dedicated mobile app, or any other application or device which is independent from the online banking frontend. The workflow of Decoupled SCA approach is a short version of Embedded SCA approach. After TPP updates PSU password via

  • PUT /v1/{payment-service}/{payment-product}/{paymentId}/authorisations/{authorisationId},

  • PUT /v1/{payment-service}/{payment-product}/{paymentId}/cancellation-authorisations/{cancellationId} or

  • PUT /v1/consents/{consentId}/authorisations/{authorisationId}

endpoints, the response from ASPSP asks PSU to proceed authorisation in dedicated device. No further authorisation calls from TPP are needed. PSU uses the dedicated device and finishes authorisation process there.

Decoupled SCA Approach uses the same list of methods as Redirect SCA Approach:

  • createCommonPaymentAuthorisation;

  • updateCommonPaymentPsuData;

  • getAuthorisationSubResources;

  • getAuthorisationScaStatus;

  • getScaApproachServiceTypeProvider.

Multicurrency Accounts

Multicurrency accounts support can be enabled in ASPSP Profile by setting multicurrencyAccountLevelSupported property to AGGREGATION_AND_SUBACCOUNT or AGGREGATION value. By default, multicurrencyAccountLevelSupported property is set to SUBACCOUNT. When TPP asks for account list information or account information (requestAccountList or requestAccountDetailForAccount method in AccountSpi), ASPSP can return null in currency field. In such case, XS2A will mark currency field with XXX text.

Get SPI SCA status

ASPSP should have a possibility to update authorisation status from bank’s internal system related to consent/payment confirmation due to the fact that not every system is capable of updating the status in CMS. For this reason AuthorisationSpi has method getScaStatus which calls ASPSP for actual status. The CMS SCA status will be updated if it is not final and differs from the bank. By default, SCA status is used from CMS on request for getting SCA status.